/**
 * @copyright Copyright (c) 2025 CSG Digital Grid Technology (Guangdong) Co., Ltd.
 * @author Xie Jinhui
 */

/* 
 * Header guard to prevent multiple inclusions of this header file
 * This ensures the compiler processes the contents only once during compilation
 * Standard technique to avoid redefinition errors in C/C++ projects
 */
#ifndef __APP_PROFILE_H__

/* 
 * Define the header guard macro to mark the beginning of protected code section
 * This macro will be checked by the preprocessor to determine if the content
 * should be included or skipped during compilation process
 */
#define __APP_PROFILE_H__

/* 
 * Include cJSON library header for JSON parsing and manipulation
 * cJSON is a lightweight JSON parser for C that provides easy-to-use API
 * for creating, parsing and modifying JSON data structures in memory
 */
#include "cJSON.h"

/* 
 * Define the default application profile filename as a string constant
 * This constant specifies the name of the JSON file that contains
 * application configuration and profile data used by the system
 */
#define APPFILE_NAME "AppProfile.json"

/* 
 * Function declaration for opening and initializing application profile control
 * @param path: String pointer to the directory path where profile file is located
 * @return: Integer status code indicating success (0) or failure (non-zero)
 * This function initializes the application profile subsystem and loads
 * the profile data from the specified file path into memory for access
 */
int open_appprofile_ctl(const char* path);

/* 
 * Function declaration for closing and cleaning up application profile control
 * @param: None
 * @return: Integer status code indicating success (0) or failure (non-zero)
 * This function performs cleanup operations including freeing allocated memory,
 * closing file handles, and releasing resources used by the profile system
 */
int close_appprofile_ctl(void);

/* 
 * Function declaration for retrieving specific information from application profile
 * @param property: String pointer to the top-level property name in JSON structure
 * @param keyname: String pointer to the specific key name within the property
 * @param valuebuff: Character buffer where the retrieved value will be stored
 * @return: Integer status code indicating success (0) or failure (non-zero)
 * This function searches the loaded profile data for a specific key-value pair
 * and copies the corresponding value to the provided output buffer
 */
int getAppProfileInfo(const char *property, const char *keyname, char *valuebuff);

/* 
 * Function declaration for obtaining the root cJSON object of application profile
 * @param: None
 * @return: Pointer to cJSON structure representing the root of profile data
 * This function provides direct access to the parsed JSON tree structure,
 * allowing advanced operations and manipulations of the profile data
 */
cJSON * get_app_profile_root(void);

/* 
 * End of header guard conditional compilation section
 * This marks the conclusion of the protected code block that is included
 * only once during the compilation process regardless of multiple includes
 */
#endif